package com.kexio.dynamic.feature.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 功能开关注解
 * 
 * 用于控制功能的启用和禁用
 * 
 * 使用示例：
 * <pre>
 * &#64;FeatureToggle("new_feature")
 * public void newFeatureMethod() {
 *     // 新功能代码，可通过配置控制启用/禁用
 * }
 * 
 * &#64;FeatureToggle(value = "premium_feature", userBased = true)
 * public void premiumFeature() {
 *     // 基于用户的功能开关
 * }
 * 
 * &#64;FeatureToggle(
 *     value = "beta_feature",
 *     percentage = 50,
 *     strategy = ToggleStrategy.PERCENTAGE
 * )
 * public void betaFeature() {
 *     // 灰度发布，50%用户可访问
 * }
 * </pre>
 * 
 * @author Kexio
 * @since 1.0.0
 */
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface FeatureToggle {

    /**
     * 功能开关名称
     */
    String value();

    /**
     * 功能开关策略
     */
    ToggleStrategy strategy() default ToggleStrategy.SIMPLE;

    /**
     * 是否基于用户的功能开关
     */
    boolean userBased() default false;

    /**
     * 是否基于租户的功能开关
     */
    boolean tenantBased() default false;

    /**
     * 灰度发布百分比（0-100）
     * 仅在strategy为PERCENTAGE时生效
     */
    int percentage() default 0;

    /**
     * 白名单用户ID列表
     * 仅在strategy为WHITELIST时生效
     */
    long[] whitelistUsers() default {};

    /**
     * 白名单租户ID列表
     * 仅在strategy为WHITELIST时生效
     */
    long[] whitelistTenants() default {};

    /**
     * 功能开关禁用时的处理策略
     */
    DisabledStrategy onDisabled() default DisabledStrategy.RETURN_NULL;

    /**
     * 功能开关禁用时的默认返回值
     * 仅在onDisabled为RETURN_DEFAULT时生效
     */
    String defaultValue() default "";

    /**
     * 功能开关禁用时的异常消息
     * 仅在onDisabled为THROW_EXCEPTION时生效
     */
    String disabledMessage() default "功能暂时不可用";

    /**
     * 是否记录功能开关访问日志
     */
    boolean logAccess() default false;

    /**
     * 功能开关描述
     */
    String description() default "";

    /**
     * 功能开关分组
     */
    String group() default "";

    /**
     * 功能开关标签
     */
    String[] tags() default {};

    /**
     * 生效时间（cron表达式）
     */
    String effectiveTime() default "";

    /**
     * 失效时间（cron表达式）
     */
    String expireTime() default "";

    /**
     * 是否使用缓存
     */
    boolean useCache() default true;

    /**
     * 缓存过期时间（秒）
     */
    int cacheTimeout() default 300;

    /**
     * 功能开关策略枚举
     */
    enum ToggleStrategy {
        /**
         * 简单开关（全局启用/禁用）
         */
        SIMPLE,
        
        /**
         * 基于用户的开关
         */
        USER_BASED,
        
        /**
         * 基于租户的开关
         */
        TENANT_BASED,
        
        /**
         * 百分比灰度发布
         */
        PERCENTAGE,
        
        /**
         * 白名单模式
         */
        WHITELIST,
        
        /**
         * 基于时间的开关
         */
        TIME_BASED,
        
        /**
         * 基于条件的开关
         */
        CONDITION_BASED,
        
        /**
         * A/B测试模式
         */
        AB_TEST
    }

    /**
     * 禁用时处理策略枚举
     */
    enum DisabledStrategy {
        /**
         * 返回null
         */
        RETURN_NULL,
        
        /**
         * 返回默认值
         */
        RETURN_DEFAULT,
        
        /**
         * 抛出异常
         */
        THROW_EXCEPTION,
        
        /**
         * 记录日志并继续
         */
        LOG_AND_CONTINUE,
        
        /**
         * 降级到备用方法
         */
        FALLBACK,
        
        /**
         * 忽略（正常执行）
         */
        IGNORE
    }
}
